scripts: clean up west build/flash/debug help
Just changes to the west help output; no functional changes expected.
Make option descriptions lowercase to match the argparse module's
conventions. When multiple sentences are required, move them to parser
prolog/epilog or argument group description sections.
Clarify some points that have confused multiple people.
Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
diff --git a/scripts/west_commands/build.py b/scripts/west_commands/build.py
index 763d384..0a286f2 100644
--- a/scripts/west_commands/build.py
+++ b/scripts/west_commands/build.py
@@ -24,14 +24,24 @@
[source_dir] -- [cmake_opt [cmake_opt ...]]
'''
-BUILD_DESCRIPTION = '''\
+BUILD_DESCRIPTION = f'''\
Convenience wrapper for building Zephyr applications.
+{FIND_BUILD_DIR_DESCRIPTION}
+
positional arguments:
- source_dir Use this path as the source directory
- cmake_opt Extra options to pass to CMake; implies -c
+ source_dir application source directory
+ cmake_opt extra options to pass to cmake; implies -c
+ (these must come after "--" as shown above)
'''
+PRISTINE_DESCRIPTION = """\
+A "pristine" build directory is empty. The -p option controls
+whether the build directory is made pristine before the build
+is done. A bare '--pristine' with no value is the same as
+--pristine=always. Setting --pristine=auto uses heuristics to
+guess if a pristine build may be necessary."""
+
def _banner(msg):
log.inf('-- west build: ' + msg, colorize=True)
@@ -86,36 +96,34 @@
# Remember to update scripts/west-completion.bash if you add or remove
# flags
- parser.add_argument('-b', '--board', help='Board to build for')
+ parser.add_argument('-b', '--board', help='board to build for')
# Hidden option for backwards compatibility
parser.add_argument('-s', '--source-dir', help=argparse.SUPPRESS)
parser.add_argument('-d', '--build-dir',
- help='Build directory. ' +
- FIND_BUILD_DIR_DESCRIPTION +
- " Otherwise the default build directory is " +
- "created and used.")
- parser.add_argument('-t', '--target',
- help='''Build system target ("usage"
- for more info; and "help" for a list)''')
- parser.add_argument('-p', '--pristine', choices=['auto', 'always',
- 'never'], action=AlwaysIfMissing, nargs='?',
- help='''Control whether the build folder is made
- pristine before running CMake. --pristine is the
- same as --pristine=always. If 'auto', it will
- be made pristine only if needed.''')
- parser.add_argument('-c', '--cmake', action='store_true',
- help='Force CMake to run')
- parser.add_argument('--cmake-only', action='store_true',
- help="Just run CMake; don't build. Implies -c.")
- parser.add_argument('-n', '--just-print', '--dry-run', '--recon',
- dest='dry_run', action='store_true',
- help='''Just print the build commands; don't run
- them''')
- parser.add_argument('-o', '--build-opt', default=[], action='append',
- help='''Options to pass to the build tool.
- May be given more than once to append multiple
- values.''')
+ help='build directory to create or use')
self.add_force_arg(parser)
+
+ group = parser.add_argument_group('cmake and build tool')
+ group.add_argument('-c', '--cmake', action='store_true',
+ help='force a cmake run')
+ group.add_argument('--cmake-only', action='store_true',
+ help="just run cmake; don't build (implies -c)")
+ group.add_argument('-t', '--target',
+ help='''run this build system target (try "-t usage"
+ or "-t help")''')
+ group.add_argument('-o', '--build-opt', default=[], action='append',
+ help='''options to pass to the build tool
+ (make or ninja); may be given more than once''')
+ group.add_argument('-n', '--just-print', '--dry-run', '--recon',
+ dest='dry_run', action='store_true',
+ help="just print build commands; don't run them")
+
+ group = parser.add_argument_group('pristine builds',
+ PRISTINE_DESCRIPTION)
+ group.add_argument('-p', '--pristine', choices=['auto', 'always',
+ 'never'], action=AlwaysIfMissing, nargs='?',
+ help='pristine build folder setting')
+
return parser
def do_run(self, args, remainder):
