From patchwork Sun Nov 11 13:14:56 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Samuel Martin X-Patchwork-Id: 198281 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from silver.osuosl.org (silver.osuosl.org [140.211.166.136]) by ozlabs.org (Postfix) with ESMTP id 1D5002C008F for ; Mon, 12 Nov 2012 00:17:55 +1100 (EST) Received: from localhost (localhost [127.0.0.1]) by silver.osuosl.org (Postfix) with ESMTP id C6C9930DF1; Sun, 11 Nov 2012 13:17:53 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from silver.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id ovUwgZqWFvHC; Sun, 11 Nov 2012 13:17:47 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by silver.osuosl.org (Postfix) with ESMTP id 1ACB03147A; Sun, 11 Nov 2012 13:16:54 +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 28D828F753 for ; Sun, 11 Nov 2012 13:15:53 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id EC9E58C2D7 for ; Sun, 11 Nov 2012 13:15:48 +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 TBYfPwXrmTQb for ; Sun, 11 Nov 2012 13:15:47 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-we0-f171.google.com (mail-we0-f171.google.com [74.125.82.171]) by whitealder.osuosl.org (Postfix) with ESMTPS id B583A8C2A6 for ; Sun, 11 Nov 2012 13:15:46 +0000 (UTC) Received: by mail-we0-f171.google.com with SMTP id s43so3028443wey.16 for ; Sun, 11 Nov 2012 05:15:46 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:to:cc:subject:date:message-id:x-mailer:in-reply-to:references; bh=Md+tJPFo1UzClWzxAwmxBcqB48xwvVDGzr5Wu6eWmu4=; b=oG7gwJxzLrDaOdLVLczIxC5OpUq0Mt8b8y0JPQzje+D+QOPPrBkeexeY/Hxcrpdu7I k2x0cgu73SAPpjoDZjZbJ5KErjQrcWYrXUZnyt7ngaMv5N8/xwbFQsFKDtGyZZkb8u2r cGjxyWS+OLj18FhTLm86golvEjZHmBDnEID1Z8Kb29/JLmdOrzjz87DXibQtKt2kB4OW SMF+OPyRivFpwrb9enrH9GDgKYMN3YWaswmzt6BTUTLGjEHwZp8vEUIGV6rEJ7xcye9C 9ZMzPX6LJMimWQTel13P40ti5ToIoAKfDHTj60LHJLwC693XpdRju+AJpUefFgkiRX2E 3RiQ== Received: by 10.180.82.162 with SMTP id j2mr10781901wiy.14.1352639746442; Sun, 11 Nov 2012 05:15:46 -0800 (PST) Received: from localhost.localdomain (ivr94-4-82-229-165-48.fbx.proxad.net. [82.229.165.48]) by mx.google.com with ESMTPS id hv4sm10262550wib.0.2012.11.11.05.15.45 (version=SSLv3 cipher=OTHER); Sun, 11 Nov 2012 05:15:45 -0800 (PST) From: Samuel Martin To: buildroot@busybox.net Date: Sun, 11 Nov 2012 14:14:56 +0100 Message-Id: <1352639701-27829-19-git-send-email-s.martin49@gmail.com> X-Mailer: git-send-email 1.8.0 In-Reply-To: <1352639701-27829-1-git-send-email-s.martin49@gmail.com> References: <1352639701-27829-1-git-send-email-s.martin49@gmail.com> Subject: [Buildroot] [PATCH 18/23] manual: add patch-policy.txt 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 Signed-off-by: Samuel Martin create mode 100644 docs/manual/patch-policy.txt diff --git a/docs/manual/developer-guide.txt b/docs/manual/developer-guide.txt index f3fc1dd..5002897 100644 --- a/docs/manual/developer-guide.txt +++ b/docs/manual/developer-guide.txt @@ -7,6 +7,8 @@ include::writing-rules.txt[] include::adding-packages.txt[] +include::patch-policy.txt[] + include::download-infra.txt[] include::board-support.txt[] diff --git a/docs/manual/patch-policy.txt b/docs/manual/patch-policy.txt new file mode 100644 index 0000000..551ea12 --- /dev/null +++ b/docs/manual/patch-policy.txt @@ -0,0 +1,128 @@ +// -*- mode:doc; -*- + +[[patch-policy]] + +Patch Policy +------------ + +While integrating a new package or updating an existing one, it may be +necessary to patch the source of the software to get it built within +Buildroot. + +Buildroot offers an infrastructure to automatically handle this during +the builds. It support several ways of applying patch sets: + +Provinding patches +~~~~~~~~~~~~~~~~~~ + +Additionnal tarball +^^^^^^^^^^^^^^^^^^^ + +If there needs to apply a patch set available as a tarball and +downloadable, then add the patch tarball to the +_PATCH+ +variable. + +Note that the patch tarballs are downloaded from the same site as the +sources. + +Within Buildroot +^^^^^^^^^^^^^^^^ + +Most of the patches are provided within Buildroot, in the package +directory, because they aim to fix cross-compilation, +libc+ support, +or whatever the reason is. + +These patch files should have the extension +*.patch+. + +A +series+ file, like +quilt+ uses it, may also be added in the +package directory. In that case, the +series+ file defines the patch +application order. + +How patches are applied +~~~~~~~~~~~~~~~~~~~~~~~ + +. Run the +_PRE_PATCH_HOOKS+ commands if defined; + +. Cleanup the build directory from any existing +*.rej+ files; + +. 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 a +series+ file exists in the package directory, then patches are + applied according to the +series+ file; ++ +* Otherwise, patch files matching `-*.patch` or + `-*.patch.` (where ++ is the architecture + name) are applied following the +ls+ command order. + +. Run the +_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 the software that is +modified. + +A message explaining what does the patch and why should be add in the +patch's header. + +You should add a +signed-off-by+ statement in the header of the each +patch to help keeping track of the changes. + +If the software is under versionning, it is recommended to use the SCM +software to generate the patch set. + +Otherwise, concatenate the header with the output of the ++diff -purN source.c.orig source.c+ command. + +At the end, the patch should look like: + +--------------- +configure.ac: add C++ support test + +signed-off-by John Doe + +--- 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 whom you are not the author, you have to add +few things in the header of the patch itself. + +Depending on whether the patch has been pick-up from the project +repository itself, or from somewhere on the web, add one of the +following tags: + +--------------- +Backported from: +--------------- + +or + +--------------- +Fetch from: +--------------- + +It is also possible to add few words about the changes that may have +been necessary if any.