From 9d097a780c0ffe2c9dbe146046d5b68123c47708 Mon Sep 17 00:00:00 2001
From: Waldemar Brodkorb <wbx@openadk.org>
Date: Sun, 16 Mar 2014 19:51:41 +0100
Subject: add OpenADK manual.

---
 docs/patch-policy.txt | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 docs/patch-policy.txt

(limited to 'docs/patch-policy.txt')

diff --git a/docs/patch-policy.txt b/docs/patch-policy.txt
new file mode 100644
index 000000000..b5a585b5e
--- /dev/null
+++ b/docs/patch-policy.txt
@@ -0,0 +1,82 @@
+// -*- 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
+OpenADK.  OpenADK offers an infrastructure to automatically handle this during
+the builds.  Patches are provided within OpenADK, in the package directory;
+these typically aim to fix cross-compilation, libc support, or other such
+issues.
+
+Normally the patches are autogenerated via:
+------------
+ $ make package=<package> update-patches
+------------
+
+Otherwise they are manually generated via:
+------------
+ $ diff -Nur <pkgname>-<pkgversion>.orig <pkgname>-<pkgversion> > package/<pkgname>/patches/xxx-description.patch 
+------------
+
+The string +xxx+ should be substituted by a number starting with 001. The
+patches will be applied in numeric order.  You should either use the automatic
+patch generation or the manual patch creation for a package. Mixed usage is not
+supported.
+
+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.
+At the end, the patch should look like:
+
+---------------
+add C++ support test
+
+--- 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.
-- 
cgit v1.2.3