ref-manual: add PACKAGE_ADD_METADATA documentation

Add a basic variable definition and a small section to the development
tasks manual for using PACKAGE_ADD_METADATA to add custom metadata to
packages.

(From yocto-docs rev: c5e4d575a771ddd1c970389ce3ace6d6abe68769)

Signed-off-by: Michael Ho <Michael.Ho@bmw.de>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 92 insertions, 0 deletions

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index e9ce182a59..605d1ad7ea 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -9057,6 +9057,9 @@
                 <listitem><para>
                     <link linkend='creating-node-package-manager-npm-packages'>Creating node package manager (NPM) packages</link>
                     </para></listitem>
+                <listitem><para>
+                    <link linkend='adding-custom-metadata-to-packages'>Adding custom metadata to packages</link>
+                    </para></listitem>
             </itemizedlist>
         </para>
 
@@ -10761,6 +10764,61 @@
                 </para>
             </section>
         </section>
+
+        <section id='adding-custom-metadata-to-packages'>
+            <title>Adding custom metadata to packages</title>
+
+            <para>
+                The variable <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ADD_METADATA'><filename>PACKAGE_ADD_METADATA</filename></ulink>
+                can be used to add additional metadata to packages. This is
+                reflected in the package control/spec file. To take the ipk
+                format for example, the CONTROL file stored inside would
+                contain the additional metadata as additional lines.
+            </para>
+
+            <para>
+                The variable can be used in multiple ways, including using
+                suffixes to set it for a specific package type and/or package.
+                Note that the order of precedence is the same as this list:
+                <itemizedlist>
+                    <listitem><para>
+                        <filename>PACKAGE_ADD_METADATA_&lt;PKGTYPE&gt;_&lt;PN&gt;</filename>
+                    </para></listitem>
+                    <listitem><para>
+                        <filename>PACKAGE_ADD_METADATA_&lt;PKGTYPE&gt;</filename>
+                    </para></listitem>
+                    <listitem><para>
+                        <filename>PACKAGE_ADD_METADATA_&lt;PN&gt;</filename>
+                    </para></listitem>
+                    <listitem><para>
+                        <filename>PACKAGE_ADD_METADATA</filename>
+                    </para></listitem>
+                </itemizedlist>
+                &lt;PKGTYPE&gt; is a parameter and expected to be a
+                distinct name of specific package type:
+                <itemizedlist>
+                    <listitem><para>IPK for .ipk packages</para></listitem>
+                    <listitem><para>DEB for .deb packages</para></listitem>
+                    <listitem><para>RPM for .rpm packages</para></listitem>
+                </itemizedlist>
+                &lt;PN&gt; is a parameter and expected to be a package name.
+            </para>
+
+            <para>
+                The variable can contain multiple [one-line] metadata fields
+                separated by the literal sequence '\n'. The separator can be
+                redefined using the variable flag <filename>separator</filename>.
+            </para>
+
+            <para>
+                The following is an example that adds two custom fields for
+                ipk packages:
+                <literallayout class='monospaced'>
+    PACKAGE_ADD_METADATA_IPK = "Vendor: CustomIpk\nGroup: Applications/Spreadsheets"
+                </literallayout>
+            </para>
+        </section>
+
     </section>
 
     <section id='efficiently-fetching-source-files-during-a-build'>
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 364cd09eb8..657f6cf3d2 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -9539,6 +9539,40 @@
             </glossdef>
         </glossentry>
 
+        <glossentry id='var-PACKAGE_ADD_METADATA'><glossterm>PACKAGE_ADD_METADATA</glossterm>
+            <info>
+                PACKAGE_ADD_METADATA[doc] = "This variable defines additional metadata to add to packages."
+            </info>
+            <glossdef>
+                <para role="glossdeffirst">
+<!--                <para role="glossdeffirst"><imagedata fileref="figures/define-generic.png" /> -->
+                    This variable defines additional metdata to add to packages.
+                </para>
+
+                <para>
+                    You may find you need to inject additional metadata into
+                    packages. This variable allows you to do that by setting
+                    the injected data as the value. Multiple fields can be
+                    added by splitting the content with the literal separator
+                    "\n".
+                </para>
+
+                <para>
+                    The suffixes '_IPK', '_DEB', or '_RPM' can be applied to
+                    the variable to do package type specific settings. It can
+                    also be made package specific by using the package name as
+                    a suffix.
+                </para>
+
+                <para>
+                    You can find out more about applying this variable in
+                    the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#adding-custom-metadata-to-packages'>Adding custom metadata to packages</ulink>"
+                    section in the Yocto Project Development Tasks Manual.
+                </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
             <info>
                 PACKAGE_ARCH[doc] = "The architecture of the resulting package or packages."