[PATCH] Documentation: Add examples to User Manual, Metadata chapter

[PATCH] Documentation: Add examples to User Manual, Metadata chapter

[Robert P. J. Day]

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

  as long as i've understood everything correctly, this is just
throwing in some physical examples of a couple concepts.

diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
index a9f5072..423d9a4 100644
--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
@@ -285,6 +285,16 @@
                 The flags are immediately set to "abc" and "123", respectively.
                 The <filename>a</filename> flag becomes "abc456".
             </para>
+
+            <para>
+                Note that there is no need to pre-define variable flags; you
+                can simply start using them.  One extremely common application
+                is to attach some brief documentation to a BitBake variable as
+                follows:
+                <literallayout class='monospaced'>
+    CACHE[doc] = "The directory holding the cache of the metadata."
+                </literallayout>
+            </para>
         </section>

         <section id='inline-python-variable-expansion'>
@@ -298,7 +308,19 @@
      DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
                 </literallayout>
                 This example results in the <filename>DATE</filename>
-                variable becoming the current date.
+                variable being set to the current date.
+            </para>
+
+            <para>
+                Probably the most common use of this feature is to extract
+                the value of variables from BitBake's internal data dictionary,
+                <filename>d</filename>. The following lines
+                select the values of, respectively, a package name and its
+                version number:
+                <literallayout class='monospaced'>
+    PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE'),d)[0] or 'defaultpkgname'}"
+    PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE'),d)[1] or '1.0'}"
+                </literallayout>
             </para>
         </section>


-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: [PATCH] Documentation: Add examples to User Manual, Metadata chapter

[Rifenbark, Scott M]

Applied with a bit of rewording and whitespace correction for the example.  Change needs to be merged to the bitbake repo.

Scott

>-----Original Message-----
>From: bitbake-devel-bounces@lists.openembedded.org [mailto:bitbake-
>devel-bounces@lists.openembedded.org] On Behalf Of Robert P. J. Day
>Sent: Wednesday, July 09, 2014 5:04 AM
>To: BitBake developer list
>Subject: [bitbake-devel] [PATCH] Documentation: Add examples to User
>Manual, Metadata chapter
>
>
>Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
>
>---
>
>  as long as i've understood everything correctly, this is just throwing in some
>physical examples of a couple concepts.
>
>diff --git a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
>b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
>index a9f5072..423d9a4 100644
>--- a/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
>+++ b/doc/bitbake-user-manual/bitbake-user-manual-metadata.xml
>@@ -285,6 +285,16 @@
>                 The flags are immediately set to "abc" and "123", respectively.
>                 The <filename>a</filename> flag becomes "abc456".
>             </para>
>+
>+            <para>
>+                Note that there is no need to pre-define variable flags; you
>+                can simply start using them.  One extremely common application
>+                is to attach some brief documentation to a BitBake variable as
>+                follows:
>+                <literallayout class='monospaced'>
>+    CACHE[doc] = "The directory holding the cache of the metadata."
>+                </literallayout>
>+            </para>
>         </section>
>
>         <section id='inline-python-variable-expansion'>
>@@ -298,7 +308,19 @@
>      DATE = "${@time.strftime('%Y%m%d',time.gmtime())}"
>                 </literallayout>
>                 This example results in the <filename>DATE</filename>
>-                variable becoming the current date.
>+                variable being set to the current date.
>+            </para>
>+
>+            <para>
>+                Probably the most common use of this feature is to extract
>+                the value of variables from BitBake's internal data dictionary,
>+                <filename>d</filename>. The following lines
>+                select the values of, respectively, a package name and its
>+                version number:
>+                <literallayout class='monospaced'>
>+    PN = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE'),d)[0] or
>'defaultpkgname'}"
>+    PV = "${@bb.parse.BBHandler.vars_from_file(d.getVar('FILE'),d)[1] or
>'1.0'}"
>+                </literallayout>
>             </para>
>         </section>
>
>
>--
>
>===========================================================
>=============
>Robert P. J. Day                                 Ottawa, Ontario, CANADA
>                        http://crashcourse.ca
>
>Twitter:                                       http://twitter.com/rpjday
>LinkedIn:                               http://ca.linkedin.com/in/rpjday
>===========================================================
>=============
>--
>_______________________________________________
>bitbake-devel mailing list
>bitbake-devel@lists.openembedded.org
>http://lists.openembedded.org/mailman/listinfo/bitbake-devel