From 6b82b70c9335d6cf6a0b84cb61392c2589ef12f7 Mon Sep 17 00:00:00 2001
From: Nitin A Kamble <nitin.a.kamble@intel.com>
Date: Tue, 1 Jun 2010 16:19:22 -0700
Subject: [PATCH] Handbook: Documentation for DISTRO_PN_ALIAS

Signed-Off-By: Nitin A Kamble <nitin.a.kamble@intel.com
---
 handbook/extendpoky.xml      | 45 +++++++++++++++++++++++++++++++++++-
 handbook/ref-variables.xml   | 17 ++++++++++++++
 handbook/ref-varlocality.xml |  4 ++++
 3 files changed, 65 insertions(+), 1 deletion(-)

diff --git a/handbook/extendpoky.xml b/handbook/extendpoky.xml
index 9d98a3bcca..9c672ec7f5 100644
--- a/handbook/extendpoky.xml
+++ b/handbook/extendpoky.xml
@@ -825,7 +825,7 @@ SRC_URI += "file://NAME-OF-PATCH.patch;patch=1"
 
     </section>
     <section id='usingpoky-configuring-LIC_FILES_CHKSUM'>
-        <title>configuring the LIC_FILES_CHKSUM variable</title>
+        <title>Configuring the LIC_FILES_CHKSUM variable</title>
         <para>
         The changes in the license text inside source code files is tracked
         using the LIC_FILES_CHKSUM metadata variable.
@@ -885,7 +885,50 @@ specify "beginline" and "endline" parameters.
             </tip>
         </section>
     </section>
+    <section id='usingpoky-configuring-DISTRO_PN_ALIAS'>
+        <title>Configuring the DISTRO_PN_ALIAS variable</title>
+        <para>
+Sometimes the names of the same packages are different in different
+linux distributions; and that can becomes an issue for the distro_check
+task to check if the given recipe package exists in other linux distros.
+This issue is avoided by defining per distro recipe name alias:
+DISTRO_PN_ALIAS
+        </para>
+
+        <section id='usingpoky-specifying-DISTRO_PN_ALIAS'>
+            <title>Specifying the DISTRO_PN_ALIAS variable </title>
+
+            <programlisting>
+DISTRO_PN_ALIAS = "distro1=package_name_alias1; distro2=package_name_alias2 \
+                    distro3=package_name_alias3; \
+                    ..."
+            </programlisting>
+            <para>
+Look at the meta/packages/xorg-app/xset_1.0.4.bb recipe file for an example.
+            </para>
+            <tip>
+                <para>
+The current code can check if the src package for a recipe exists in the latest
+releases of these distributions automatically.
+                </para>
+                <programlisting>
+Fedora, OpenSuSE, Debian, Ubuntu, Mandriva
+                </programlisting>
+                <para>
+For example, this command will generate a report, listing which linux distros include the
+sources for each of the poky recipe.
+                </para>
+                <programlisting>
+bitbake world -f -c distro_check
+                </programlisting>
+                <para>
+The results will be stored in the build/tmp/log/distro_check-${DATETIME}.results file.
+                </para>
+            </tip>
+        </section>
+    </section>
 </chapter>
+
 <!-- 
 vim: expandtab tw=80 ts=4 
 -->
diff --git a/handbook/ref-variables.xml b/handbook/ref-variables.xml
index b4d5639ec1..7bbcdb81f0 100644
--- a/handbook/ref-variables.xml
+++ b/handbook/ref-variables.xml
@@ -216,6 +216,19 @@
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
+            <glossdef>
+                <para>Alias names of the recipe in various Linux distributions.  </para>
+                <para>See the "meta/package/xorg-app/xset_1.0.4.bb" file for an example</para>
+                <para>More information in 
+                    <link
+                        linkend='usingpoky-configuring-DISTRO_PN_ALIAS'>
+                        Configuring the DISTRO_PN_ALIAS variable section
+                    </link>
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
             <glossdef>
                 <para>Version of distribution</para>
@@ -406,6 +419,10 @@
                 <para> This is an optional variable now. And the plan is to make
                 it a required variable in the future </para>
                 <para>See the "meta/package/zlib/zlib_${PV}.bb" file for an example</para>
+
+                <para>More information in <link
+                    linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
+                    Configuring the LIC_FILES_CHKSUM variable section</link></para>
             </glossdef>
         </glossentry>
 
diff --git a/handbook/ref-varlocality.xml b/handbook/ref-varlocality.xml
index f8cfc4fad4..fb5679499a 100644
--- a/handbook/ref-varlocality.xml
+++ b/handbook/ref-varlocality.xml
@@ -187,6 +187,10 @@
         <title>Recipe Variables - Extra Build Information</title>
 
         <itemizedlist>
+            <listitem>
+                <para><glossterm><link
+                linkend='var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</link></glossterm></para>
+            </listitem>
             <listitem>
                 <para><glossterm><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></glossterm></para>
             </listitem>