bug 9962: improve -v, -D documentation
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
@@ -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
@@ -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
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.
Signed-off-by Diana Thayer <[email protected]>--- 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@@ -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 specifythis 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
thisdoc/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 areprinted
+ to stdout; -DD sets the debug level to 2,
wheredoc/bitbake-user-manual/bitbake-user-manual-intro.xml +2
-0+ both bb.debug(1, ...) and bb.debug(2, ...) + messages are printed; etc. Without -D, nodebug
+ 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.
-SSIGNATURE_HANDLER, --dump-signatures=SIGNATURE_HANDLER
Dump out the signature construction
information, withlib/bb/main.py +0
-0@@ -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 tostdout (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 onlybb.debug(1, ...)messages are
printed "
+ "to stdout; -DD sets the debug level to 2,
where "
+ "bothbb.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
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
Quoted 23 lines · Diana Thayer
Per bug-9962, expanded and clarified documentation for -v, --verbose and -D, --debug.
Signed-off-by Diana Thayer <[email protected]>--- 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@@ -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, withlib/bb/main.py +13
-2@@ -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
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 printbb.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 + bothbb.debug(1, ...)andbb.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