bitbake: Upgrade from 1.4 -> 1.7.4ish

git-svn-id: https://svn.o-hand.com/repos/poky/trunk@863 311d38ba-8fff-0310-9ca6-ca027cbcb966

bitbake/doc/manual/usermanual.xml

@@ -17,7 +17,7 @@
             <holder>Phil Blundell</holder>
         </copyright>
         <legalnotice>
-            <para>This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit <ulink url="http://creativecommons.org/licenses/by/2.0/">http://creativecommons.org/licenses/by/2.0/</ulink> or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.</para>
+            <para>This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit <ulink url="http://creativecommons.org/licenses/by/2.5/">http://creativecommons.org/licenses/by/2.5/</ulink> or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.</para>
         </legalnotice>
     </bookinfo>
     <chapter>
@@ -195,7 +195,7 @@ addtask printdate before do_build</screen></para>
             <section>
                 <title>Events</title>
                 <para><emphasis>NOTE:</emphasis> This is only supported in .bb and .bbclass files.</para>
-                <para>BitBake also implements a means of registering event handlers.  Events are triggered at certain points during operation, such as, the beginning of operation against a given .bb, the start of a given task, task failure, task success, et cetera.  The intent was to make it easy to do things like email notifications on build failure.</para>
+                <para>BitBake allows to install event handlers.  Events are triggered at certain points during operation, such as, the beginning of operation against a given .bb, the start of a given task, task failure, task success, et cetera.  The intent was to make it easy to do things like email notifications on build failure.</para>
                 <para><screen>addhandler myclass_eventhandler
 python myclass_eventhandler() {
     from bb.event import NotHandled, getName
@@ -205,6 +205,7 @@ python myclass_eventhandler() {
     print "The file we run for is %s" % data.getVar('FILE', e.data, True)
 
     return NotHandled
+}
 </screen></para><para>
 This event handler gets called every time an event is triggered. A global variable <varname>e</varname> is defined. <varname>e</varname>.data contains an instance of bb.data. With the getName(<varname>e</varname>)
 method one can get the name of the triggered event.</para><para>The above event handler prints the name
@@ -344,15 +345,19 @@ options:
                         cannot be remade, the other dependencies of these
                         targets can be processed all the same.
   -f, --force           force run of specified cmd, regardless of stamp status
-  -i, --interactive     drop into the interactive mode.
+  -i, --interactive     drop into the interactive mode also called the BitBake
+                        shell.
   -c CMD, --cmd=CMD     Specify task to execute. Note that this only executes
                         the specified task for the providee and the packages
                         it depends on, i.e. 'compile' does not implicitly call
                         stage for the dependencies (IOW: use only if you know
-                        what you are doing)
+                        what you are doing). Depending on the base.bbclass a
+                        listtaks tasks is defined and will show available
+                        tasks
   -r FILE, --read=FILE  read the specified file before bitbake.conf
   -v, --verbose         output more chit-chat to the terminal
-  -D, --debug           Increase the debug level
+  -D, --debug           Increase the debug level. You can specify this more
+                        than once.
   -n, --dry-run         don't execute, just go through the motions
   -p, --parse-only      quit after parsing the BB files (developers only)
   -d, --disable-psyco   disable using the psyco just-in-time compiler (not
@@ -360,6 +365,12 @@ options:
   -s, --show-versions   show current and preferred versions of all packages
   -e, --environment     show the global or per-package environment (this is
                         what used to be bbread)
+  -g, --graphviz        emit the dependency trees of the specified packages in
+                        the dot syntax
+  -I IGNORED_DOT_DEPS, --ignore-deps=IGNORED_DOT_DEPS
+                        Stop processing at the given list of dependencies when
+                        generating dependency graphs. This can help to make
+                        the graph more appealing
 
 </screen>
                 </para>
@@ -386,6 +397,14 @@ options:
                     <screen><prompt>$ </prompt>bitbake virtual/whatever</screen>
                     <screen><prompt>$ </prompt>bitbake -c clean virtual/whatever</screen>
                 </example>
+                <example>
+                    <title>Generating dependency graphs</title>
+                    <para>BitBake is able to generate dependency graphs using the dot syntax. These graphs can be converted
+to images using the <application>dot</application> application from <ulink url="http://www.graphviz.org">graphviz</ulink>. 
+Three files will be written into the current working directory, <emphasis>depends.dot</emphasis> containing <varname>DEPENDS</varname> variables, <emphasis>rdepends.dot</emphasis> and <emphasis>alldepends.dot</emphasis> containing both <varname>DEPENDS</varname> and <varname>RDEPENDS</varname>. To stop depending on common depends one can use the <prompt>-I depend</prompt> to omit these from the graph. This can lead to more readable graphs. E.g. this way <varname>DEPENDS</varname> from inherited classes, e.g. base.bbclass, can be removed from the graph.</para>
+                    <screen><prompt>$ </prompt>bitbake -g blah</screen>
+                    <screen><prompt>$ </prompt>bitbake -g -I virtual/whatever -I bloom blah</screen>
+                </example>
                 </para>
             </section>
             <section>