Skip to contentSkip to conversation

bug 9962: improve -v, -D documentation

PATCH In review Diana Thayer 3 participants 5 messages Mar 21, 2017 – Mar 30, 2017

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 bug 9962: improve -v, -D documentation

Per bug-9962, expanded and clarified documentation for -v, --verbose and -D, --debug.

---
 doc/bitbake-user-manual/bitbake-user-manual-intro.xml | 16 +++++++++++++---
 lib/bb/main.py                                        | 15 +++++++++++++--
 2 files changed, 26 insertions(+), 5 deletions(-)
doc/bitbake-user-manual/bitbake-user-manual-intro.xml +13 -3
index 7248a0b..5bbfc67 100644
@@ -504,9 +504,19 @@
                              Read the specified file before bitbake.conf.
        -R POSTFILE, --postread=POSTFILE
                              Read the specified file after bitbake.conf.
-       -v, --verbose         Output more log message data to the terminal.
-       -D, --debug           Increase the debug level. You can specify this more
-                             than once.
+       -v, --verbose         Enable tracing of shell tasks (with 'set -x').
+                             Also print bb.note(...) messages to stdout (in
+                             addition to writing them to ${T}/log.do_<task>).
+       -D, --debug           Increase the debug level. You can specify this
+                             more than once. -D sets the debug level to 1,
+                             where only bb.debug(1, ...) messages are printed
+                             to stdout; -DD sets the debug level to 2, where
+                             both bb.debug(1, ...) and bb.debug(2, ...)
+                             messages are printed; etc. Without -D, no debug
+                             messages are printed. Note that -D only affects
+                             output to stdout. All debug messages are written
+                             to ${T}/log.do_taskname, regardless of the debug
+                             level.
        -n, --dry-run         Don't execute, just go through the motions.
        -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
                              Dump out the signature construction information, with
lib/bb/main.py +13 -2
index b3cd2cf..8c948c2 100755
@@ -174,10 +174,21 @@ class BitBakeConfigParameters(cookerdata.ConfigParameters):
                           help="Read the specified file after bitbake.conf.")
 
         parser.add_option("-v", "--verbose", action="store_true", dest="verbose", default=False,
-                          help="Output more log message data to the terminal.")
+                          help="Enable tracing of shell tasks (with 'set -x'). "
+                               "Also print bb.note(...) messages to stdout (in "
+                               "addition to writing them to ${T}/log.do_<task>).")
 
         parser.add_option("-D", "--debug", action="count", dest="debug", default=0,
-                          help="Increase the debug level. You can specify this more than once.")
+                          help="Increase the debug level. You can specify this "
+                               "more than once. -D sets the debug level to 1, "
+                               "where only bb.debug(1, ...) messages are printed "
+                               "to stdout; -DD sets the debug level to 2, where "
+                               "both bb.debug(1, ...) and bb.debug(2, ...) "
+                               "messages are printed; etc. Without -D, no debug "
+                               "messages are printed. Note that -D only affects "
+                               "output to stdout. All debug messages are written "
+                               "to ${T}/log.do_taskname, regardless of the debug "
+                               "level.")
 
         parser.add_option("-q", "--quiet", action="count", dest="quiet", default=0,
                           help="Output less log message data to the terminal. You can specify this more than once.")
Signature · 1 line
2.7.4
#1 lore raw

Hi!

I did my best to follow patch submission guidelines
<https://www.openembedded.org/wiki/How_to_submit_a_patch_to_OpenEmbedded>
and code styleguide <https://www.openembedded.org/wiki/Styleguide> but this is my very first patch to anything in the Yocto project. Please let me know if and how I can improve future patch submissions! I figured since it's my first time, I would follow up and say hello :)

This patch addresses bug 9962
<https://bugzilla.yoctoproject.org/show_bug.cgi?id=9962> by updating the documentation of bitbake's -v and -D CLI options. I copied the updated text directly from the bug report, and changed it both in the code and in the user manual.

Anyway hi! I hope to contribute more soon :)

Quoted 102 lines · Diana Thayer

Per bug-9962, expanded and clarified documentation for -v, --verbose and -D, --debug.

---
 doc/bitbake-user-manual/bitbake-user-manual-intro.xml | 16
+++++++++++++---
 lib/bb/main.py                                        | 15 +++++++++++++--
 2 files changed, 26 insertions(+), 5 deletions(-)
doc/bitbake-user-manual/bitbake-user-manual-intro.xml +0 -2
index 7248a0b..5bbfc67 100644
@@ -504,9 +504,19 @@
                              Read the specified file before bitbake.conf.
        -R POSTFILE, --postread=POSTFILE
                              Read the specified file after bitbake.conf.
-       -v, --verbose         Output more log message data to the terminal.
-       -D, --debug           Increase the debug level. You can specify

this more

doc/bitbake-user-manual/bitbake-user-manual-intro.xml +2 -2
-                             than once.
+       -v, --verbose         Enable tracing of shell tasks (with 'set
-x').
+                             Also print bb.note(...) messages to stdout

(in
+ addition to writing them to
${T}/log.do_<task>).
+ -D, --debug Increase the debug level. You can specify
this

doc/bitbake-user-manual/bitbake-user-manual-intro.xml +2 -0
+                             more than once. -D sets the debug level to 1,
+                             where only bb.debug(1, ...) messages are

printed
+ to stdout; -DD sets the debug level to 2,
where

doc/bitbake-user-manual/bitbake-user-manual-intro.xml +2 -0
+                             both bb.debug(1, ...) and bb.debug(2, ...)
+                             messages are printed; etc. Without -D, no

debug
+ messages are printed. Note that -D only
affects
+ output to stdout. All debug messages are
written
+ to ${T}/log.do_taskname, regardless of the
debug
+ level.
-n, --dry-run Don't execute, just go through the motions.
-S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
Dump out the signature construction
information, with

lib/bb/main.py +0 -0
index b3cd2cf..8c948c2 100755
@@ -174,10 +174,21 @@ class BitBakeConfigParameters(

cookerdata.ConfigParameters):
help="Read the specified file after
bitbake.conf.")

         parser.add_option("-v", "--verbose", action="store_true",

dest="verbose", default=False,
- help="Output more log message data to the
terminal.")

lib/bb/main.py +2 -1
+                          help="Enable tracing of shell tasks (with 'set
-x'). "
+                               "Also print bb.note(...) messages to

stdout (in "
+ "addition to writing them to
${T}/log.do_<task>).")

         parser.add_option("-D", "--debug", action="count", dest="debug",

default=0,
- help="Increase the debug level. You can specify
this more than once.")
+ help="Increase the debug level. You can specify
this "
+ "more than once. -D sets the debug level
to 1, "
+ "where only bb.debug(1, ...) messages are
printed "
+ "to stdout; -DD sets the debug level to 2,
where "
+ "both bb.debug(1, ...) and bb.debug(2,
...) "
+ "messages are printed; etc. Without -D, no
debug "
+ "messages are printed. Note that -D only
affects "
+ "output to stdout. All debug messages are
written "
+ "to ${T}/log.do_taskname, regardless of
the debug "
+ "level.")

         parser.add_option("-q", "--quiet", action="count", dest="quiet",

default=0,
help="Output less log message data to the
terminal. You can specify this more than once.")
--
2.7.4

#2 lore raw
Quoted 8 lines · Diana Thayer

Hi!

I did my best to follow patch submission guidelines and code styleguide but this is my very first patch to anything in the Yocto project. Please let me know if and how I can improve future patch submissions! I figured since it's my first time, I would follow up and say hello :)

Quoted 6 lines

This patch addresses bug 9962 by updating the documentation of bitbake's -v and -D CLI options. I copied the updated text directly from the bug report, and changed it both in the code and in the user manual.

Anyway hi! I hope to contribute more soon :)

Hi!

Thanks for taking the time to submit the patch and sorry for the delay in getting back to you. I've just queued this in master-next for further testing. The patch itself is great, I did have to tweak the commit message a bit. In particular:

I added "main: " as a prefix to the shortlog since this indicates there the change was made. I also changed the bug reference to our standard form [YOCTO #XXXX] so that when we search commits for bug references, its in a standard form. The commit message needs to stand alone without someone needing to read the bug, that is there just as a useful link for more information. All just minor formatting tweaks really though.

Cheers,

Richard

#3 lore raw
In reply to Diana Thayer
Quoted 23 lines · Diana Thayer

Per bug-9962, expanded and clarified documentation for -v, --verbose and -D, --debug.

---
 doc/bitbake-user-manual/bitbake-user-manual-intro.xml | 16 +++++++++++++---
 lib/bb/main.py                                        | 15 +++++++++++++--
 2 files changed, 26 insertions(+), 5 deletions(-)
doc/bitbake-user-manual/bitbake-user-manual-intro.xml +3 -3
index 7248a0b..5bbfc67 100644
@@ -504,9 +504,19 @@
                              Read the specified file before bitbake.conf.
        -R POSTFILE, --postread=POSTFILE
                              Read the specified file after bitbake.conf.
-       -v, --verbose         Output more log message data to the terminal.
-       -D, --debug           Increase the debug level. You can specify this more
-                             than once.
+       -v, --verbose         Enable tracing of shell tasks (with 'set -x').
+                             Also print bb.note(...) messages to stdout (in
+                             addition to writing them to ${T}/log.do_<task>).

doc/bitbake-user-manual/bitbake-user-manual-intro.xml line 519

Quoted 10 lines
doc/bitbake-user-manual/bitbake-user-manual-intro.xml +10 -0
+       -D, --debug           Increase the debug level. You can specify this
+                             more than once. -D sets the debug level to 1,
+                             where only bb.debug(1, ...) messages are printed
+                             to stdout; -DD sets the debug level to 2, where
+                             both bb.debug(1, ...) and bb.debug(2, ...)
+                             messages are printed; etc. Without -D, no debug
+                             messages are printed. Note that -D only affects
+                             output to stdout. All debug messages are written
+                             to ${T}/log.do_taskname, regardless of the debug
+                             level.

I think the description is fine for -D/--debug , but I am not sure if this is the place to describe that level N includes N-1, etc.. This is something standard, and describing here make it a bit verbose.

Quoted 34 lines
doc/bitbake-user-manual/bitbake-user-manual-intro.xml +0 -0
        -n, --dry-run         Don't execute, just go through the motions.
        -S SIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
                              Dump out the signature construction information, with
lib/bb/main.py +13 -2
index b3cd2cf..8c948c2 100755
@@ -174,10 +174,21 @@ class BitBakeConfigParameters(cookerdata.ConfigParameters):
                           help="Read the specified file after bitbake.conf.")
 
         parser.add_option("-v", "--verbose", action="store_true", dest="verbose", default=False,
-                          help="Output more log message data to the terminal.")
+                          help="Enable tracing of shell tasks (with 'set -x'). "
+                               "Also print bb.note(...) messages to stdout (in "
+                               "addition to writing them to ${T}/log.do_<task>).")
 
         parser.add_option("-D", "--debug", action="count", dest="debug", default=0,
-                          help="Increase the debug level. You can specify this more than once.")
+                          help="Increase the debug level. You can specify this "
+                               "more than once. -D sets the debug level to 1, "
+                               "where only bb.debug(1, ...) messages are printed "
+                               "to stdout; -DD sets the debug level to 2, where "
+                               "both bb.debug(1, ...) and bb.debug(2, ...) "
+                               "messages are printed; etc. Without -D, no debug "
+                               "messages are printed. Note that -D only affects "
+                               "output to stdout. All debug messages are written "
+                               "to ${T}/log.do_taskname, regardless of the debug "
+                               "level.")
 
         parser.add_option("-q", "--quiet", action="count", dest="quiet", default=0,
                           help="Output less log message data to the terminal. You can specify this more than once.")
Signature · 1 line
2.7.4
#4 lore raw
Quoted 21 lines · Leonardo Sandoval
Quoted 12 lines · Diana Thayer

                 Read the specified file before
bitbake.conf.
        -R POSTFILE, --postread=POSTFILE
                              Read the specified file after bitbake.conf. -       -v, --verbose         Output more log message data to the terminal. -       -D, --debug           Increase the debug level. You can specify this more -                             than once.
+       -v, --verbose         Enable tracing of shell tasks (with 'set -x'). +                             Also print bb.note(...) messages to stdout (in +                             addition to writing them to ${T}/log.do_). +       -D, --debug           Increase the debug level. You can specify this +                             more than once. -D sets the debug level to 1,

Quoted 8 lines

+                             where only bb.debug(1, ...) messages are printed +                             to stdout; -DD sets the debug level to 2, where +                             both bb.debug(1, ...) and bb.debug(2, ...) +                             messages are printed; etc. Without -D, no debug +                             messages are printed. Note that -D only affects +                             output to stdout. All debug messages are written +                             to ${T}/log.do_taskname, regardless of the debug +                             level.

Quoted 3 lines

I think the description is fine for -D/--debug , but I am not sure if this is the place to describe that level N includes N-1, etc.. This is something standard, and describing here make it a bit verbose.

FWIW I tend to agree with you. Further patches are welcome.

Cheers,

Richard